歡迎來到《Go Clean Architecture API 開發全攻略》系列的第一篇文章！

近年來，Go 語言以其簡潔的語法、出色的併發性能和高效的編譯速度，在後端開發領域迅速崛起。

特別是在雲原生和微服務的浪潮中，Go 已成為許多團隊的首選語言。

然而，僅僅學會 Go 的語法並不足以開發出一個能在生產環境中穩定運行的服務。

一個成功的專案不僅需要實現業務功能，更需要具備良好的架構、清晰的結構、以及高度的可維護性與可測試性。

本系列文章的目的，就是帶領你走過這條從「知道語法」到「精通工程實踐」的道路。我們將從一個空白的資料夾開始，一步步搭建起一個功能完整、結構清晰、品質卓越的 API 服務。

我們將要打造什麼？

在本系列中，我們將共同打造一個基礎但五臟俱全的 使用者認證 API 服務。這個服務將包含以下核心功能：

1. 使用者註冊：允許新使用者建立帳號。
2. 使用者登入：驗證使用者身份並核發 JWT (JSON Web Token)。
3. 使用者資訊查詢：一個受保護的端點，使用者必須提供有效的 JWT 才能存取自己的資訊。

雖然功能簡單，但它涵蓋了 API 開發中最常見的場景：資料庫互動、身份驗證、設定管理、錯誤處理等。

我們將藉此專案，來實踐業界推崇的 六角形架構（Hexagonal Architecture），也常被稱為 乾淨架構（Clean Architecture）。

我們的技術工具箱 (Tech Stack)

工欲善其事，必先利其器。在專案中，我們將採用以下在 Go 生態中廣受歡迎且經過考驗的工具：

• 語言 (Language): Go - 我們的主角。
• Web 框架 (Framework): Gin - 一個高效能、API 友善的 Web 框架。
• 資料庫互動 (ORM): GORM - 功能強大且廣泛使用的 ORM 函式庫。
• 資料庫遷移 (Migration): golang-migrate - 用於管理資料庫結構的變更。
• 容器化 (Containerization): Docker & Docker Compose - 用於建立一致、可攜的開發與部署環境。
• 設定管理 (Configuration): Viper - 強大的設定檔管理工具，能處理多種格式的設定檔與環境變數。
• API 文件 (API Docs): Swagger/OpenAPI - 自動生成互動式 API 文件，方便前後端協作。
• 程式碼品質 (Linter): golangci-lint - 集合多種 Linter 的工具，強力保障程式碼風格與品質。

準備工作 (Prerequisites)

在開始之前，請確保你的開發環境中已安裝以下工具：

• Go (建議版本 1.21 或以上)
• Docker 和 Docker Compose
• 你喜歡的程式碼編輯器 (例如 VS Code)

第一步：建立專案結構

一個好的開始是成功的一半。讓我們先為專案建立一個清晰的目錄結構。這個結構基於六角形架構的理念，旨在將不同職責的程式碼進行隔離。

打開你的終端機，執行以下指令：

# 建立專案根目錄
mkdir go-clean-project
cd go-clean-project

# 建立核心目錄結構
mkdir -p cmd/api
mkdir -p internal
mkdir -p deployments
mkdir -p docs
mkdir -p pkg

# 初始化 Go Modules
go mod init go-clean-project

讓我們簡單解釋一下這些頂層目錄的職責：

• cmd/: 專案的進入點。如果我們的專案未來有多個執行檔（例如一個 API 服務，一個背景 worker），它們的 main.go 都會放在這裡。
• internal/: 專案的核心邏輯所在。這是 Go 語言的一個特殊目錄，放在這裡的程式碼只能被同一個專案（go-clean-project）下的程式碼引用，無法被外部專案匯入，這有助於保護你的內部實作。
• deployments/: 存放與部署相關的檔案，例如資料庫遷移檔案、Dockerfile 等。
• docs/: 存放專案文件，以及 Swagger API 文件。
• pkg/: 存放可以被外部專案安全引用的程式碼。在我們的專案初期，可能不會用到太多，但建立這個目錄是一個好的實踐。

總結

恭喜你！你已經成功邁出了第一步：了解了我們的目標、技術選型，並建立了專案的基礎骨架。這是一個穩固的起點。

在下一篇文章中，我們將深入探討為何選擇「六角形架構」，並解釋這種架構如何幫助我們打造一個真正可維護、可擴展的應用程式。